Add 'agent: BoltAgent' listener argument #1437

mwbrooks · 2026-02-11T01:02:46Z

Changelog

Do not include in our Changelog because this is marked as an experimental feature.

Summary

This pull request adds a agent: BoltAgent listener argument, which will be used to access AI agent-related features such as chat_stream and more.

Introduces BoltAgent and AsyncBoltAgent classes that provide a convenient chat_stream() method pre-configured with event context defaults (channel_id, thread_ts, team_id, user_id)
Wires agent into Bolt's kwargs injection system so listeners can declare it as a parameter (e.g. def handle(agent: BoltAgent)) or access it via context.agent
BoltAgent construction is deferred - only created when the listener actually requests the agent or args parameter, avoiding unnecessary object creation on every dispatch

Experimental

The agent: BoltAgent class and listener argument are marked as an experimental feature. We are categorizing experimental features as semver:patch until the experimental status is removed.

No exists tests were modified and the goal is to be a low risk feature to add to main.

Example

@app.event("app_mention")
def handle_mention(agent: BoltAgent):
    stream = agent.chat_stream()
    stream.append(markdown_text="Hello!")
    stream.stop()

Known limitations

chat_stream() currently only works when thread_ts is available in the event context (DMs and threaded replies). Top-level channel messages do not have thread_ts, and ts is not yet provided to BoltAgent - tracked as a FIXME in the code. I've experimented with a solution, but I'd prefer to introduce it in a separate PR so that we can review it independently.

Testing

→ Modified Sample App with agent: BoltAgent and agent.chat_stream()

# Create a modified copy of AI Agent Sample app that uses `agent.chat_stream()`
$ slack create my-app --template https://github.com/slack-samples/bolt-python-assistant-template --branch feat-agent-argument
$ cd my-app/

# Setup the app
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt

# Run the app
$ slack run

# Test the app
# → Open DM → Send a message → Confirm it works
# → @Mention Reply in thread → Confirm it works

# Clean up
$ slack delete -f
$ cd ..
$ rm -rf my-app/

Requirements

Please read the Contributing guidelines and Code of Conduct before creating this issue or pull request. By submitting, you are agreeing to those rules.

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.
I've run ./scripts/install_all_and_run_tests.sh after making the changes.

codecov · 2026-02-11T01:03:19Z

Codecov Report

❌ Patch coverage is 91.04478% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.59%. Comparing base (868cedb) to head (5335855).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
slack_bolt/agent/agent.py	88.88%	2 Missing ⚠️
slack_bolt/agent/async_agent.py	88.88%	2 Missing ⚠️
slack_bolt/kwargs_injection/async_utils.py	75.00%	1 Missing ⚠️
slack_bolt/kwargs_injection/utils.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1437      +/-   ##
==========================================
+ Coverage   90.54%   90.59%   +0.05%     
==========================================
  Files         222      225       +3     
  Lines        7129     7190      +61     
==========================================
+ Hits         6455     6514      +59     
- Misses        674      676       +2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

…ependency AsyncBoltAgent imports AsyncWebClient which requires aiohttp. Eagerly importing it from the agent package __init__ breaks environments where aiohttp is not installed, since slack_bolt/__init__.py imports BoltAgent from this package. Follows the existing convention of not adding async module imports at the top level.

… tests

…7 compat Replace AsyncMock usage with coroutine-returning MagicMock wrappers, matching the pattern used in the sync test suite. This avoids the Python 3.8+ AsyncMock and the need for the mock backport package.

mwbrooks

Comments for the kind and knowledgeable reviewers!

mwbrooks · 2026-02-11T05:38:21Z

slack_bolt/agent/agent.py

+    Experimental:
+        This API is experimental and may change in future releases.


note: We're using an "Experimental" warning while we developer this feature. Rather than working on a long-standing branch, we'd like to merge into main under a semver:patch then release a semver:minor when the experimental status is removed.

mwbrooks · 2026-02-11T05:39:00Z

slack_bolt/agent/agent.py

+        FIXME: chat_stream() only works when thread_ts is available (DMs and threaded replies).
+        It does not work on channel messages because ts is not provided to BoltAgent yet.


note: Important callout. I'd like to add ts support in a follow-up PR so that we can discuss the best approach.

mwbrooks · 2026-02-11T05:40:24Z

slack_bolt/kwargs_injection/async_utils.py

    next_keys_required: bool = True,  # False for listeners / middleware / error handlers
 ) -> Dict[str, Any]:
-    all_available_args = {
+    all_available_args: Dict[str, Any] = {


note: This fixed a linter warning

mwbrooks · 2026-02-11T05:40:45Z

slack_bolt/kwargs_injection/async_utils.py

        if name == "args":
            if isinstance(request, AsyncBoltRequest):
-                kwargs[name] = AsyncArgs(**all_available_args)  # type: ignore[arg-type]
+                kwargs[name] = AsyncArgs(**all_available_args)


note: The above fix allows us to remove this type ignore

WilliamBergamin

Awesome work 💯 this is already starting to take shape 🚀 left a few comments

One more thing around testing, what do you think about adding some unit tests in tests/slack_bolt(_async)/kwargs_injection/test_args.py that ensure build_required_kwargs only creates a BoltAgent when the agent keyword argument is present in required_arg_names

WilliamBergamin · 2026-02-11T15:00:33Z

slack_bolt/kwargs_injection/async_utils.py

+    if "agent" in required_arg_names or "args" in required_arg_names:
+        all_available_args["agent"] = request.context.agent


Clever 💯 I like this and wonder if we should follow this pattern for other keyword arguments 🚀

What do you think about including a warning here that informs developers that the agent is an experimental feature subject to change?

From what I can tell we should be able to do this by taking advantage of the FutureWarning like this

import warnings class ExperimentalWarning(FutureWarning): """Warning for features that are still in experimental phase.""" pass warnings.warn( "agent is experimental and may change in future versions.", category=ExperimentalWarning, stacklevel=2 )

IIUC every time a handler processes a request and uses the "agent" kwargs, this warning would be printed, this might be a bit annoying but it would be clear

WilliamBergamin · 2026-02-11T15:03:38Z

slack_bolt/__init__.py

 from .response import BoltResponse

 # AI Agents & Assistants
+from .agent import BoltAgent


🤔 Maybe we should wait until the feature is GA before exporting it here?

Developers should still be able to import the class directly with something like
from slack_bolt.agent import BoltAgent

WilliamBergamin · 2026-02-11T15:35:01Z

slack_bolt/context/async_context.py

+if TYPE_CHECKING:
+    from slack_bolt.agent.async_agent import AsyncBoltAgent
+


TIL: TYPE_CHECKING, it seems awesome and maybe we can use it elsewhere to improve our types checking for async stuff

IIUC this is to ensure that we

Do not import AsyncBoltAgent whenever AsyncBoltContext is imported

Static type checking around AsyncBoltAgent passes

AsyncBoltAgent is only imported when context.agent is invoked

WilliamBergamin · 2026-02-11T15:44:33Z

slack_bolt/agent/agent.py

+        resolved_channel = channel or self._channel_id
+        resolved_thread_ts = thread_ts or self._thread_ts


I'm wondering here if falling back to the class instances channel_id, thread_ts, team_id and user_id is the best behavior 🤔

Like if a developer only passes one of these parameters and are unaware of the the fallback values they could end up chat streaming to the wrong location?
I'm not super familiar with chat_stream so this might be a non issue

💭 i agree with @WilliamBergamin! channel_id and thread_ts seem to work as a pair so if a user changes one they should be aware they need to change the other. Maybe we throw a warning when one of these params is changed but not the other 🤔 ?

WilliamBergamin · 2026-02-11T15:56:53Z

tests/scenario_tests/test_events_agent.py

+    def test_agent_chat_stream_overrides_context_defaults(self):
+        """Explicit kwargs to chat_stream() override context defaults."""
+        client = MagicMock(spec=WebClient)
+        client.chat_stream.return_value = MagicMock(spec=ChatStream)
+
+        agent = BoltAgentDirect(
+            client=client,
+            channel_id="C111",
+            thread_ts="1234567890.123456",
+            team_id="T111",
+            user_id="W222",
+        )
+        stream = agent.chat_stream(
+            channel="C999",
+            thread_ts="9999999999.999999",
+            recipient_team_id="T999",
+            recipient_user_id="U999",
+        )
+
+        client.chat_stream.assert_called_once_with(
+            channel="C999",
+            thread_ts="9999999999.999999",
+            recipient_team_id="T999",
+            recipient_user_id="U999",
+        )
+        assert stream is not None


What do you think about creating a tests.slack_bolt.agent and tests.slack_bolt_async.agent directory where unit tests dedicated to the BoltAgent like these ones can live?

agreed 🙌 it looks like we're mixing unit tests with full app scenarios 🤔 might be nice to follow up on this in another pr ⭐

srtaalej

left some comments but its LGTM! thank you for bringing these changes in so quickly 🚀 ⭐ ⭐ ⭐

srtaalej · 2026-02-11T20:53:11Z

tests/scenario_tests/test_events_agent.py

+    def test_agent_chat_stream_overrides_context_defaults(self):
+        """Explicit kwargs to chat_stream() override context defaults."""
+        client = MagicMock(spec=WebClient)
+        client.chat_stream.return_value = MagicMock(spec=ChatStream)
+
+        agent = BoltAgentDirect(
+            client=client,
+            channel_id="C111",
+            thread_ts="1234567890.123456",
+            team_id="T111",
+            user_id="W222",
+        )
+        stream = agent.chat_stream(
+            channel="C999",
+            thread_ts="9999999999.999999",
+            recipient_team_id="T999",
+            recipient_user_id="U999",
+        )
+
+        client.chat_stream.assert_called_once_with(
+            channel="C999",
+            thread_ts="9999999999.999999",
+            recipient_team_id="T999",
+            recipient_user_id="U999",
+        )
+        assert stream is not None


agreed 🙌 it looks like we're mixing unit tests with full app scenarios 🤔 might be nice to follow up on this in another pr ⭐

mwbrooks added 4 commits February 9, 2026 21:21

feat: add 'agent: BoltAgent' listener argument

fadc1a4

fix: export AsyncBoltAgent from agent module

10c56e9

perf: defer BoltAgent construction to when listener requests it

e6e456a

fixme: note chat_stream limitation with channel messages missing ts

d0752cb

mwbrooks added this to the 1.27.1 milestone Feb 11, 2026

mwbrooks self-assigned this Feb 11, 2026

mwbrooks requested a review from a team as a code owner February 11, 2026 01:02

mwbrooks added enhancement New feature or request area:async area:sync tests semver:patch labels Feb 11, 2026

Merge branch 'main' into feat-agent-argument

c332128

mwbrooks marked this pull request as draft February 11, 2026 01:04

mwbrooks added 3 commits February 10, 2026 20:27

fix: handle AsyncMock import for older Python versions in async agent…

7722f3e

… tests

fix: remove AsyncMock dependency from async agent tests for Python 3.…

c7e0089

…7 compat Replace AsyncMock usage with coroutine-returning MagicMock wrappers, matching the pattern used in the sync test suite. This avoids the Python 3.8+ AsyncMock and the need for the mock backport package.

mwbrooks marked this pull request as ready for review February 11, 2026 05:36

mwbrooks commented Feb 11, 2026

View reviewed changes

WilliamBergamin reviewed Feb 11, 2026

View reviewed changes

chore: use relative imports in agent/__init__.py

5335855

srtaalej approved these changes Feb 11, 2026

View reviewed changes

		Experimental:
		This API is experimental and may change in future releases.

		FIXME: chat_stream() only works when thread_ts is available (DMs and threaded replies).
		It does not work on channel messages because ts is not provided to BoltAgent yet.

		if "agent" in required_arg_names or "args" in required_arg_names:
		all_available_args["agent"] = request.context.agent

		if TYPE_CHECKING:
		from slack_bolt.agent.async_agent import AsyncBoltAgent

		resolved_channel = channel or self._channel_id
		resolved_thread_ts = thread_ts or self._thread_ts

Add 'agent: BoltAgent' listener argument #1437

Are you sure you want to change the base?

Add 'agent: BoltAgent' listener argument #1437

Conversation

mwbrooks commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

Summary

Experimental

Example

Known limitations

Testing

Category

Requirements

Uh oh!

codecov bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mwbrooks left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

srtaalej left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mwbrooks commented Feb 11, 2026 •

edited

Loading

codecov bot commented Feb 11, 2026 •

edited

Loading